/*
 * Copyright (c) 2022 Huawei Device Co., Ltd.
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * @file native_huks_param.h
 *
 * @brief 提供参数集构造、使用和销毁的API。
 *
 * @since 9
 * @version 1.0
 *
 * @vee OH_Huks_InitParamSet
 * @vee OH_Huks_AddParams
 * @vee OH_Huks_BuildParamSet
 * @vee OH_Huks_FreeParamSet
 * @vee OH_Huks_CopyParamSet
 * @vee OH_Huks_GetParam
 * @vee OH_Huks_FreshParamSet
 * @vee OH_Huks_isParamSetTagValid
 * @vee OH_Huks_isParamSetValid
 * @vee OH_Huks_CheckParamMatch
 */

#ifndef NATIVE_HUKS_PARAM_H
#define NATIVE_HUKS_PARAM_H

#include "native_huks_type.h"

#define OH_HUKS_PARAM_SET_MAX_SIZE (4 * 1024 * 1024)
#define OH_HUKS_DEFAULT_PARAM_SET_SIZE 512
#define OH_HUKS_DEFAULT_PARAM_CNT ((uint32_t)(OH_HUKS_DEFAULT_PARAM_SET_SIZE / sizeof(struct OH_Huks_Param)))
#define OH_HUKS_TAG_TYPE_MASK (0xF << 28)

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief 初始化OH_Huks_ParamSet结构体。
 *
 * @param paramSet 表示待初始化的结构体，必须为NULL。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */
int32_t OH_Huks_InitParamSet(struct OH_Huks_ParamSet **paramSet);

/**
 * @brief 往OH_Huks_ParamSet里面添加参数，使用前需要调用OH_Huks_InitParamSet初始化结构体。
 *
 * @param paramSet 表示添加参数之前的参数集，为调用OH_Huks_InitParamSet后的结构体。
 * @param params 表示待添加的一个或多个参数。
 * @param paramCnt 表示params里面对应的参数个数。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */

int32_t OH_Huks_AddParams(struct OH_Huks_ParamSet *paramSet,
    const struct OH_Huks_Param *params, uint32_t paramCnt);

/**
 * @brief 生成最终的参数集，在调用OH_Huks_InitParamSet、OH_Huks_AddParams后使用。
 *
 * @param paramSet 表示添加参数之后的入参参数集，为调用OH_Huks_InitParamSet、OH_Huks_AddParams后的结构体。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */
int32_t OH_Huks_BuildParamSet(struct OH_Huks_ParamSet **paramSet);

/**
 * @brief 释放参数集。
 *
 * @param paramSet 表示待释放的参数集。
 * @since 9
 * @version 1.0
 */
void OH_Huks_FreeParamSet(struct OH_Huks_ParamSet **paramSet);

/**
 * @brief 复制参数集。
 *
 * @param fromParamSet 表示要被复制的参数集。
 * @param fromParamSetSize 表示被复制的参数集占用内存的大小。
 * @param paramSet 表示生成新的参数集。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */
int32_t OH_Huks_CopyParamSet(const struct OH_Huks_ParamSet *fromParamSet,
    uint32_t fromParamSetSize, struct OH_Huks_ParamSet **paramSet);

/**
 * @brief 根据TAG从参数集paramSet中获取对应的参数。
 *
 * @param paramSet 表示参数集，非空，需要满足参数要求。
 * @param tag 表示需要获取的参数的TAG,从enum OH_Huks_Tag中获取
 * @param param 表示获取到的参数，无需释放。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */
int32_t OH_Huks_GetParam(const struct OH_Huks_ParamSet *paramSet, uint32_t tag,
    struct OH_Huks_Param **param);

/**
 * @brief 刷新参数集。
 *
 * @param paramSet 表示待刷新的参数集。
 * @param isCopy 表示是否要刷新参数集内存中的struct HksBlob型的参数数据。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */
int32_t OH_Huks_FreshParamSet(struct OH_Huks_ParamSet *paramSet, bool isCopy);

/**
 * @brief 检查参数集中的参数是否有效、是否有重复。
 *
 * @param paramSet 表示待检查的参数集。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */
int32_t OH_Huks_isParamSetTagValid(const struct OH_Huks_ParamSet *paramSet);

/**
 * @brief 检查参数集是否有效。
 *
 * @param paramSet 表示待检查的参数集。
 * @param size 表示参数集占用的内存大小。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */
int32_t OH_Huks_isParamSetValid(const struct OH_Huks_ParamSet *paramSet, uint32_t size);

/**
 * @brief 比较两个参数是否相同
 *
 * @param baseParam 表示被比较的参数。
 * @param param 表示比较的参数。
 * @return 返回执行的状态代码。
 * @since 9
 * @version 1.0
 */
int32_t OH_Huks_CheckParamMatch(const struct OH_Huks_Param *baseParam, const struct OH_Huks_Param *param);

#ifdef __cplusplus
}
#endif

#endif /* NATIVE_HUKS_PARAM_H */